.TH std::flat_map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::flat_map \- std::flat_map

.SH Synopsis
   Defined in header <flat_map>
   template<

       class Key,
       class T,
       class Compare = std::less<Key>,         (since C++23)
       class KeyContainer = std::vector<Key>,
       class MappedContainer = std::vector<T>

   > class flat_map;

   The flat map is a container adaptor that gives the functionality of an associative
   container that contains key-value pairs with unique keys. Keys are sorted by using
   the comparison function Compare.

   The class template flat_map acts as a wrapper to the two underlying containers,
   passed as objects of type KeyContainer and MappedContainer respectively. The first
   container is sorted, and for each key its corresponding value is in the second
   container at the same index (offset). The number of elements in both containers is
   the same.

   Everywhere the standard library uses the Compare requirements, uniqueness is
   determined by using the equivalence relation. Informally, two objects a and b are
   considered equivalent if neither compares less than the other: !comp(a, b) &&
   !comp(b, a).

   std::flat_map meets the requirements of Container, ReversibleContainer, optional
   container requirements, and all requirements of AssociativeContainer (including
   logarithmic search complexity), except that:

     * requirements related to nodes are not applicable,
     * iterator invalidation requirements differ,
     * the complexity of insertion and erasure operations is linear.

   A flat map supports most AssociativeContainer's operations that use unique keys.

.SH Template parameters

   Key             - The type of the keys. The program is ill-formed if Key is not the
                     same type as KeyContainer::value_type.
   T               - The type of mapped values. The program is ill-formed if T is not
                     the same type as MappedContainer::value_type.
   Compare         - A Compare type providing a strict weak ordering.
                     The types of the underlying SequenceContainer to store keys and
                     mapped values correspondingly. The iterators of such containers
                     should satisfy LegacyRandomAccessIterator or model
   KeyContainer    - random_access_iterator. Invocations of their member functions size
   MappedContainer   and max_size should not exit via an exception.

                     The standard containers std::vector and std::deque satisfy these
                     requirements.

.SH Member types

   Member type            Definition
   key_container_type     KeyContainer
   mapped_container_type  MappedContainer
   key_type               Key
   mapped_type            T
   value_type             std::pair<key_type, mapped_type>
   key_compare            Compare
   reference              std::pair<const key_type&, mapped_type&>
   const_reference        std::pair<const key_type&, const mapped_type&>
   size_type              std::size_t
   difference_type        std::ptrdiff_t
   iterator               implementation-defined LegacyInputIterator and
                          random_access_iterator to value_type
   const_iterator         implementation-defined LegacyInputIterator and
                          random_access_iterator to const value_type
   reverse_iterator       std::reverse_iterator<iterator>
   const_reverse_iterator std::reverse_iterator<const_iterator>
                          type describing the underlying containers

                          struct containers
   containers             {
                              key_container_type keys;
                              mapped_container_type values;
                          };

.SH Member classes

   value_compare compares objects of type value_type
                 \fI(class)\fP

.SH Member objects

   Member name       Definition
   c (private)       the object of type containers
                     (exposition-only member object*)
   compare (private) the comparison function object of type key_compare
                     (exposition-only member object*)

.SH Member functions

   constructor           constructs the flat_map
                         \fI(public member function)\fP
   destructor            destroys every element of the container adaptor
   (implicitly declared) \fI(public member function)\fP
   operator=             assigns values to the container adaptor
                         \fI(public member function)\fP
.SH Element access
   at                    access specified element with bounds checking
                         \fI(public member function)\fP
   operator[]            access or insert specified element
                         \fI(public member function)\fP
.SH Iterators
   begin                 returns an iterator to the beginning
   cbegin                \fI(public member function)\fP
   end                   returns an iterator to the end
   cend                  \fI(public member function)\fP
   rbegin                returns a reverse iterator to the beginning
   crbegin               \fI(public member function)\fP
   rend                  returns a reverse iterator to the end
   crend                 \fI(public member function)\fP
.SH Capacity
   empty                 checks whether the container adaptor is empty
                         \fI(public member function)\fP
   size                  returns the number of elements
                         \fI(public member function)\fP
   max_size              returns the maximum possible number of elements
                         \fI(public member function)\fP
.SH Modifiers
   emplace               constructs element in-place
                         \fI(public member function)\fP
   emplace_hint          constructs elements in-place using a hint
                         \fI(public member function)\fP
                         inserts in-place if the key does not exist, does nothing if
   try_emplace           the key exists
                         \fI(public member function)\fP
   insert                inserts elements
                         \fI(public member function)\fP
   insert_range          inserts a range of elements
                         \fI(public member function)\fP
                         inserts an element or assigns to the current element if the
   insert_or_assign      key already exists
                         \fI(public member function)\fP
   extract               extracts the underlying containers
                         \fI(public member function)\fP
   replace               replaces the underlying containers
                         \fI(public member function)\fP
   erase                 erases elements
                         \fI(public member function)\fP
   swap                  swaps the contents
                         \fI(public member function)\fP
   clear                 clears the contents
                         \fI(public member function)\fP
.SH Lookup
   find                  finds element with specific key
                         \fI(public member function)\fP
   count                 returns the number of elements matching specific key
                         \fI(public member function)\fP
   contains              checks if the container contains element with specific key
                         \fI(public member function)\fP
                         returns an iterator to the first element not less than the
   lower_bound           given key
                         \fI(public member function)\fP
                         returns an iterator to the first element greater than the
   upper_bound           given key
                         \fI(public member function)\fP
   equal_range           returns range of elements matching a specific key
                         \fI(public member function)\fP
.SH Observers
   key_comp              returns the function that compares keys
                         \fI(public member function)\fP
                         returns the function that compares keys in objects of type
   value_comp            value_type
                         \fI(public member function)\fP
   keys                  direct access to the underlying keys container
                         \fI(public member function)\fP
   values                direct access to the underlying values container
                         \fI(public member function)\fP

.SH Non-member functions

   operator==               lexicographically compares the values of two flat_maps
   operator<=>              \fI(function template)\fP
   (C++23)
   std::swap(std::flat_map) specializes the std::swap algorithm
   (C++23)                  \fI(function template)\fP
   erase_if(std::flat_map)  erases all elements satisfying specific criteria
   (C++23)                  \fI(function template)\fP

.SH Helper classes

   std::uses_allocator<std::flat_map> specializes the std::uses_allocator type trait
   (C++23)                            \fI(class template specialization)\fP

   Tags

   sorted_unique   indicates that elements of a range are sorted and unique
   sorted_unique_t (tag)
   (C++23)

   Deduction guides

.SH Notes

   The member types iterator and const_iterator may be aliases to the same type. This
   means defining a pair of function overloads using the two types as parameter types
   may violate the One Definition Rule. Since iterator is convertible to
   const_iterator, a single function with a const_iterator as parameter type will work
   instead.

   Feature-test macro  Value    Std                 Feature
   __cpp_lib_flat_map 202207L (C++23) std::flat_map and std::flat_multimap

.SH Example

    This section is incomplete
    Reason: no example

.SH See also

   flat_multimap adapts two containers to provide a collection of key-value pairs,
   (C++23)       sorted by keys
                 \fI(class template)\fP
   map           collection of key-value pairs, sorted by keys, keys are unique
                 \fI(class template)\fP
   unordered_map collection of key-value pairs, hashed by keys, keys are unique
   \fI(C++11)\fP       \fI(class template)\fP

.SH Categories:
     * Todo without reason
     * Todo no example
